<HTML><HEAD><TITLE>functor(?Term, ?Functor, ?Arity)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Term Manipulation</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>functor(?Term, ?Functor, ?Arity)</H1>
Succeeds if the compound term Term has functor Functor and arity Arity or
if Term and Functor are atomic and equal, and Arity is 0.


<DL>
<DT><EM>Term</EM></DT>
<DD>Prolog term.
</DD>
<DT><EM>Functor</EM></DT>
<DD>Atomic term or variable.
</DD>
<DT><EM>Arity</EM></DT>
<DD>Positive integer or variable.
</DD>
</DL>
<H2>Description</H2>
   If Term is instantiated, its functor is unified with Functor and its
   arity with Arity.

<P>
   If Term is not instantiated, it is bound to a term with functor Functor
   and arity Arity.

<P>
   This predicate regards atomic terms (number, atom or string) as
   terms with arity 0 and functor equal to the term.

<P>
   To query only the arity of a term, arity/2 can be used instead of functor/3.

<H3>Modes and Determinism</H3><UL>
<LI>functor(+, -, -) is det
<LI>functor(-, +, +) is det
</UL>
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>Term and either (or both) of Functor and Arity are    uninstantiated (non-coroutine mode only).
<DT><EM>(5) type error </EM>
<DD>Arity is neither a variable nor an integer.
<DT><EM>(5) type error </EM>
<DD>Functor is neither a variable nor an atomic term.
<DT><EM>(6) out of range </EM>
<DD>Arity is a negative integer.
</DL>
<H2>Examples</H2>
<PRE>
   Success:
   functor(f(1,2),f,2).
   functor(f(1,2),F,A).  (gives F=f, A=2).
   functor(T,f,3).       (gives T=f(_g50, _g52, _g54)).
   functor(T,.,2).       (gives T=[_g48 | _g50]).
   functor([],F,A).      (gives F=[], A=0).
   functor("s",F,A).     (gives F="s", A=0).
   Fail:
   functor(f(1,2),f,3).
   functor("compound(g)",compound,1).
   functor(f(1,2),"f",2).
   Error:
   functor(T,F,A).                    (Error 4).
   functor("f",[f],X).                (Error 5).
   functor(X,[a],Y).                  (Error 5).
   functor(f(1,2),f,-1).              (Error 6).



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/termmanip/arity-2.html">arity / 2</A>, <A HREF="../../kernel/termmanip/EDD-2.html">=.. / 2</A>, <A HREF="../../kernel/termmanip/arg-3.html">arg / 3</A>
</BODY></HTML>
